<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>Drag and Drop</title>
    <link rel="stylesheet" href="http://yui.yahooapis.com/3.4.0pr3/build/cssgrids/grids-min.css">
    <link rel="stylesheet" href="../assets/css/main.css">
    <link rel="stylesheet" href="../assets/vendor/prettify/prettify-min.css">
    <script src="../../build/yui/yui-min.js"></script>
</head>
<body>

<div id="doc">
    <h1>Drag and Drop</h1>

    
        <a href="#toc" class="jump">Jump to Table of Contents</a>
    

    <div class="yui3-g">
        <div id="main" class="yui3-u">
            <div class="content"><div class="intro">
    <p> The Drag and Drop Utility allows you to create a draggable interface efficiently, buffering you from browser-level abnormalities and enabling you to focus on the interesting logic surrounding your particular implementation. This component enables you to create a variety of standard draggable objects with just a few lines of code and then, using its extensive API, add your own specific implementation logic. </p>
    <p>For more information about drag and drop as a design pattern, see the <a href="http://developer.yahoo.com/ypatterns/parent_dragdrop.php">Yahoo! Design Pattern Library</a>.</p>
</div>

<h2 id="getting-started">Getting Started</h2>

<p>
To include the source files for Drag and Drop and its dependencies, first load
the YUI seed file if you haven't already loaded it.
</p>

<pre class="code prettyprint">&lt;script src=&quot;http:&#x2F;&#x2F;yui.yahooapis.com&#x2F;3.4.0&#x2F;build&#x2F;yui&#x2F;yui-min.js&quot;&gt;&lt;&#x2F;script&gt;</pre>


<p>
Next, create a new YUI instance for your application and populate it with the
modules you need by specifying them as arguments to the <code>YUI().use()</code> method.
YUI will automatically load any dependencies required by the modules you
specify.
</p>

<pre class="code prettyprint">&#x2F;&#x2F; Create a new YUI instance and populate it with the required modules.
YUI().use(&#x27;dd&#x27;, function (Y) {
    &#x2F;&#x2F; Drag and Drop is available and ready for use. Add implementation
    &#x2F;&#x2F; code here.
});</pre>


<p>
For more information on creating YUI instances and on the
<a href="http://yuilibrary.com/yui/docs/api/classes/YUI.html#method_use"><code>use()</code> method</a>, see the
documentation for the <a href="../yui/index.html">YUI Global object</a>.
</p>


<h2 id="using-drag-and-drop">Using Drag and Drop</h2>

<h3 id="basic-drag">Basic Drag</h3>
<p>You create a simple Drag instance by including the <code>dd-drag</code> module and using the following code:</p>

<pre class="code prettyprint">YUI().use(&#x27;dd-drag&#x27;, function(Y) {
    var dd = new Y.DD.Drag({
        node: &#x27;#drag&#x27;
    });
});</pre>


<h3 id="basic-proxy-drag">Basic Proxy Drag</h3>
<p>You create a simple Proxy Drag instance by including the <code>dd-drag</code> and <code>dd-proxy</code> modules and using the following code:</p>

<pre class="code prettyprint">YUI().use(&#x27;dd-drag&#x27;, &#x27;dd-proxy&#x27;, function(Y) {
    var dd = new Y.DD.Drag({
        node: &#x27;#drag&#x27;
    }).plug(Y.Plugin.DDProxy); &#x2F;&#x2F;This config option makes the node a Proxy Drag
});</pre>


<h3 id="basic-drop-target">Basic Drop Target</h3>
<p>You create a simple Drop Target instance by including the <code>dd-drop</code> module and using the following code:</p>

<pre class="code prettyprint">YUI().use(&#x27;dd-drop&#x27;, function(Y) {
    var drop = new Y.DD.Drop({
        node: &#x27;#drop&#x27;
    });
});</pre>


<h2 id="events">Events</h2>

<p>Drag and Drop for YUI 3 has been been packed with useful events to allow the implementer to control the end user experience.</p>
<p><em>* All Drag and Drop events bubble, by default, to the Drag and Drop Manager.</em></p>

<table>
    <thead>
        <tr>
            <th>Event</th>
            <th>Target</th>
            <th>Preventable</th>
            <th>Stoppable</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><code>drag:mouseDown</code></td>
            <td>Drag</td>
            <td>yes</td>
            <td>yes</td>
            <td>Handles the mousedown/touchstart DOM event, checks to see if you have a valid handle then starts the drag timers.</td>
        </tr>
        <tr>
            <td><code>drag:afterMouseDown</code></td>
            <td>Drag</td>
            <td>no</td>
            <td>no</td>
            <td>Fires after the mousedown/touchstart event has been cleared.</td>
        </tr>
        <tr>
            <td><code>drag:mouseup</code></td>
            <td>Drag</td>
            <td>yes</td>
            <td>yes</td>
            <td>Fires the mouseup event.</td>
        </tr>
        <tr>
            <td><code>drag:align</code></td>
            <td>Drag</td>
            <td>yes</td>
            <td>yes</td>
            <td>Fires when this node is aligned.</td>
        </tr>
        <tr>
            <td><code>drag:removeHandle</code></td>
            <td>Drag</td>
            <td>no</td>
            <td>no</td>
            <td>Fires after a handle is removed.</td>
        </tr>
        <tr>
            <td><code>drag:addHandle</code></td>
            <td>Drag</td>
            <td>no</td>
            <td>no</td>
            <td>Fires after a handle is added.</td>
        </tr>
        <tr>
            <td><code>drag:removeInvalid</code></td>
            <td>Drag</td>
            <td>no</td>
            <td>no</td>
            <td>Fires after an invalid selector is removed.</td>
        </tr>
        <tr>
            <td><code>drag:addInvalid</code></td>
            <td>Drag</td>
            <td>no</td>
            <td>no</td>
            <td>Fires after an invalid selector is added.</td>
        </tr>
        <tr>
            <td><code>drag:start</code></td>
            <td>Drag</td>
            <td>no</td>
            <td>no</td>
            <td>Fires at the start of a drag operation.</td>
        </tr>
        <tr>
            <td><code>drag:end</code></td>
            <td>Drag</td>
            <td>yes</td>
            <td>yes</td>
            <td>Fires at the end of a drag operation.</td>
        </tr>
        <tr>
            <td><code>drag:drag</code></td>
            <td>Drag</td>
            <td>yes</td>
            <td>yes</td>
            <td>Fires every mousemove/touchmove during a drag operation.</td>
        </tr>
        <tr>
            <td><code>drag:over</code></td>
            <td>Drag</td>
            <td>no</td>
            <td>no</td>
            <td>Fires when this node is over a Drop Target. (Fired from dd-drop)</td>
        </tr>
        <tr>
            <td><code>drag:enter</code></td>
            <td>Drag</td>
            <td>no</td>
            <td>no</td>
            <td>Fires when this node enters a Drop Target. (Fired from dd-drop)</td>
        </tr>
        <tr>
            <td><code>drag:exit</code></td>
            <td>Drag</td>
            <td>no</td>
            <td>no</td>
            <td>Fires when this node exits a Drop Target. (Fired from dd-drop)</td>
        </tr>
        <tr>
            <td><code>drag:drophit</code></td>
            <td>Drag</td>
            <td>no</td>
            <td>no</td>
            <td>Fires when this node is dropped on a valid Drop Target. (Fired from dd-ddm-drop)</td>
        </tr>
        <tr>
            <td><code>drag:dropmiss</code></td>
            <td>Drag</td>
            <td>no</td>
            <td>no</td>
            <td>Fires when this node is dropped on an invalid Drop Target. (Fired from dd-ddm-drop)</td>
        </tr>
        <tr>
            <td><code>drop:over</code></td>
            <td>Drop</td>
            <td>no</td>
            <td>no</td>
            <td>Fires when a drag element is over this target.</td>
        </tr>
        <tr>
            <td><code>drop:enter</code></td>
            <td>Drop</td>
            <td>no</td>
            <td>no</td>
            <td>Fires when a drag element enters this target.</td>
        </tr>
        <tr>
            <td><code>drop:exit</code></td>
            <td>Drop</td>
            <td>no</td>
            <td>no</td>
            <td>Fires when a drag element exits this target.</td>
        </tr>
        <tr>
            <td><code>drop:hit</code></td>
            <td>Drop</td>
            <td>no</td>
            <td>no</td>
            <td>Fires when a draggable node is dropped on this Drop Target. (Fired from dd-ddm-drop)</td>
        </tr>
    </tbody>
</table>
				
<h3 id="bubbling">Event Bubbling</h3>

<p>To allow for a truly Event driven application, all Drag and Drop related events are bubbled to the <code>DragDropMgr</code>.</p>
<p>This allows you to listen for all Drag and Drop events from a central location, per YUI instance.</p>
<p>This approach is also handy for situations where you are dynamically adding and removing items.</p>
<p>So instead of doing this:</p>

<pre class="code prettyprint">var doSomething = function() {
    Y.log(&#x27;Do Something Here&#x27;);
};
dd1.on(&#x27;drag:drag&#x27;, doSomething);
dd2.on(&#x27;drag:drag&#x27;, doSomething);
dd3.on(&#x27;drag:drag&#x27;, doSomething);
dd4.on(&#x27;drag:drag&#x27;, doSomething);
dd5.on(&#x27;drag:drag&#x27;, doSomething);
dd6.on(&#x27;drag:drag&#x27;, doSomething);
dd7.on(&#x27;drag:drag&#x27;, doSomething);
dd8.on(&#x27;drag:drag&#x27;, doSomething);
dd9.on(&#x27;drag:drag&#x27;, doSomething);</pre>


<p>You can now do this:</p>

<pre class="code prettyprint">var doSomething = function() {
    Y.log(&#x27;Do Something Here&#x27;);
};
Y.DD.DDM.on(&#x27;drag:drag&#x27;, doSomething);</pre>


<h2 id="delegate">Delegate Dragging</h2>
<p>Delegate dragging allows you to create a "list/group" of draggable items that are under a common "container". Using this approach, you can have hundreds of draggable items, yet only have one object created under the hood.</p>
<p>This approach is also handy for situations where you are dynamically adding and removing items from the "list" and need to make them draggable. Using <code>Delegate</code> you wouldn't have to create a new <code>drag</code> instance when adding or removing it.</p>

<pre class="code prettyprint">YUI().use(&#x27;dd-delegate&#x27;, function(Y) {
    var del = new Y.DD.Delegate({
        container: &#x27;#demo&#x27;, &#x2F;&#x2F;The common container
        nodes: &#x27;.item&#x27; &#x2F;&#x2F;The items to make draggable
    });
});</pre>


<p><strong>Note:</strong> <code>DD.Delegate</code> does not auto find your drop target items, if you change the <code>nodes</code> under the hood (add or remove) you need to call <code>delegate.syncTargets();</code> to manage them.</p>


<h2 id="cssclasses">CSS Class Names</h2>

<p>The Drag and Drop Utility adds CSS class names for important moments in the drag and drop operation. Below you will find the list of these class names.</p>
<p>The Drag and Drop Utility doesn't ship with a default skin, so no style rules are attached to these class names. That is completely left up to the implementer.</p>
<p><strong>Note: </strong> As of version 3.1.0, Drag and Drop changed it's classname prefix from <code>yui-dd</code> to <code>yui3-dd</code> to mimic the global change in skinning.</p>
<table>
    <thead>
        <tr>
            <th>Class Name</th>
            <th>Target</th>
            <th>State</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td nowrap="nowrap"><code>yui3-dd-draggable</code></td>
            <td>Drag</td>
            <td>Given to all Drag Nodes</td>
        </tr>
        <tr>
            <td nowrap="nowrap"><code>yui3-dd-locked</code></td>
            <td>Drag</td>
            <td>Added when a Drag instance is locked</td>
        </tr>
        <tr>
            <td nowrap="nowrap"><code>yui3-dd-dragging</code></td>
            <td>Drag</td>
            <td>Added while a Drag instance is active</td>
        </tr>
        <tr>
            <td nowrap="nowrap"><code>yui3-dd-proxy</code></td>
            <td>Proxy</td>
            <td>Given to the Proxy Node</td>
        </tr>
        <tr>
            <td nowrap="nowrap"><code>yui3-dd-drop</code></td>
            <td>Drop</td>
            <td>Given to all Drop Targets</td>
        </tr>
        <tr>
            <td nowrap="nowrap"><code>yui3-dd-drop-locked</code></td>
            <td>Drop</td>
            <td>Added when a Drop instance is locked</td>
        </tr>
        <tr>
            <td nowrap="nowrap"><code>yui3-dd-drop-active-valid</code></td>
            <td>Drop</td>
            <td>Added to a Drop when it is an valid target for the current drag operation</td>
        </tr>
        <tr>
            <td nowrap="nowrap"><code>yui3-dd-drop-active-invalid</code></td>
            <td>Drop</td>
            <td>Added to a Drop when it is an invalid target for the current drag operation</td>
        </tr>
        <tr>
            <td nowrap="nowrap"><code>yui3-dd-drop-over</code></td>
            <td>Drop</td>
            <td>Added when a Drag instance is over this Drop Target</td>
        </tr>
    </tbody>
</table>

<h2 id="gestures">Touch/Gesture Support</h2>

<p>Native gesture support was added to DD in 3.2.0. This support is transparent and the implementor should not have to do anything to use this functionality. When <code>dd</code> is used, loader will check the device to see if it contains support for Gesture Events, if the device supports these events the <code>dd-gestures</code> module will automatically be loaded as well as it's dependencies. At this point, DD will operate as usual but it will utilize the native gesture events instead of mouse based events.</p>




<h2 id="modules">Module Descriptions</h2>

<p>Drag and Drop for YUI 3 has been broken up into several modules to allow you, as the implementer, to pick how you want it to work and what code you need on your page.</p>
<table>
    <thead>
        <tr>
            <th>Module Name</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td nowrap="nowrap"><code>dd-drag</code></td>
            <td>Main drag class, this makes something draggable.</td>
        </tr>
        <tr>
            <td nowrap="nowrap"><code>dd-proxy</code></td>
            <td>Adds proxy support to the main drag class.</td>
        </tr>
        <tr>
            <td nowrap="nowrap"><code>dd-constrain</code></td>
            <td>Adds constrain support to the main drag class.</td>
        </tr>
        <tr>
            <td nowrap="nowrap"><code>dd-scroll</code></td>
            <td>Adds node and window based scroll support.</td>
        </tr>
        <tr>
            <td nowrap="nowrap"><code>dd-delegate</code></td>
            <td>Provides the ability to drag multiple nodes under a container element using only one Y.DD.Drag instance as a delegate.</td>
        </tr>
        <tr>
            <td nowrap="nowrap"><code>dd-drop</code></td>
            <td>Drop Support, this is the support for all drop targets.</td>
        </tr>
        <tr>
            <td nowrap="nowrap"><code>dd</code></td>
            <td>All of the Drag and Drop modules rolled up into one file.</td>
        </tr>                           
        <tr>
            <th colspan="2">Other Included Modules</th>
        </tr>
        <tr>
            <td nowrap="nowrap"><code>dd-ddm-base</code></td>
            <td>Base DragDrop Manager, required to make something draggable.</td>
        </tr>
        <tr>
            <td nowrap="nowrap"><code>dd-ddm</code></td>
            <td>Adds shim support, only needed when you need to drag over something that steals mouse events or you are targeting.</td>
        </tr>
        <tr>
            <td nowrap="nowrap"><code>dd-ddm-drop</code></td>
            <td>Adds Drop support, only required when you have drop targets you need to interact with.</td>
        </tr>
    </tbody>
</table>

<h2 id="plugins">DD Plugins</h2>

<p><strong>In 3.2.0, some modules have been removed from the rollup and were converted to DD Plugins.</strong> Below are the list of plugins that are no longer in the <code>dd</code> rollup.</p>
<table>
    <thead>
        <tr>
            <th>Plugin</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td nowrap="nowrap"><code>dd-plugin</code></td>
            <td>Node plugin for Drag</td>
        </tr>
        <tr>
            <td nowrap="nowrap"><code>dd-drop-plugin</code></td>
            <td>Node plugin for Drop</td>
        </tr>
        <tr>
            <td nowrap="nowrap"><code>dd-gestures</code></td>
            <td>Node plugin for Gesture support. This module is automatically loaded by loader when <code>dd</code> is used on a device that supports gestures.</td>
        </tr>
    </tbody>
</table>
</div>
        </div>

        <div id="sidebar" class="yui3-u">
            
                <div id="toc" class="sidebox">
                    <div class="hd">
                        <h2 class="no-toc">Table of Contents</h2>
                    </div>

                    <div class="bd">
                        <ul class="toc">
<li>
<a href="#getting-started">Getting Started</a>
</li>
<li>
<a href="#using-drag-and-drop">Using Drag and Drop</a>
<ul class="toc">
<li>
<a href="#basic-drag">Basic Drag</a>
</li>
<li>
<a href="#basic-proxy-drag">Basic Proxy Drag</a>
</li>
<li>
<a href="#basic-drop-target">Basic Drop Target</a>
</li>
</ul>
</li>
<li>
<a href="#events">Events</a>
<ul class="toc">
<li>
<a href="#bubbling">Event Bubbling</a>
</li>
</ul>
</li>
<li>
<a href="#delegate">Delegate Dragging</a>
</li>
<li>
<a href="#cssclasses">CSS Class Names</a>
</li>
<li>
<a href="#gestures">Touch/Gesture Support</a>
</li>
<li>
<a href="#modules">Module Descriptions</a>
</li>
<li>
<a href="#plugins">DD Plugins</a>
</li>
</ul>
                    </div>
                </div>
            

            
                <div class="sidebox">
                    <div class="hd">
                        <h2 class="no-toc">Examples</h2>
                    </div>

                    <div class="bd">
                        <ul class="examples">
                            
                                
                                    <li data-description="A simple drag interaction that doesn&#x27;t require a drop interaction.">
                                        <a href="simple-drag.html">Simple Drag</a>
                                    </li>
                                
                            
                                
                                    <li data-description="How to apply the Drag Plugin to a node.">
                                        <a href="drag-plugin.html">Drag - Node plugin</a>
                                    </li>
                                
                            
                                
                                    <li data-description="A simple proxy drag interaction that doesn&#x27;t require a drop interaction.">
                                        <a href="proxy-drag.html">Drag - Proxy</a>
                                    </li>
                                
                            
                                
                                    <li data-description="How to constrain a draggable Node to another Node&#x27;s region.">
                                        <a href="constrained-drag.html">Drag - Constrained to a Region</a>
                                    </li>
                                
                            
                                
                                    <li data-description="Using interaction groups, this example demonstrates how to tie into the Drag &amp; Drop Utility&#x27;s interesting moments to provide visual affordances for the current drag operation.">
                                        <a href="groups-drag.html">Drag - Interaction Groups</a>
                                    </li>
                                
                            
                                
                                    <li data-description="The use of the drag shim when dragging nodes over other troublesome nodes.">
                                        <a href="shim-drag.html">Using the Drag Shim</a>
                                    </li>
                                
                            
                                
                                    <li data-description="How to use the Drop Target events to code your application.">
                                        <a href="drop-code.html">Using Drop Based Coding</a>
                                    </li>
                                
                            
                                
                                    <li data-description="How you can use the DD Scroll plugin to scroll the browser window as you drag.">
                                        <a href="winscroll.html">Window Scrolling</a>
                                    </li>
                                
                            
                                
                                    <li data-description="How to use DD.Delegate to create a scalable solution which supports multiple draggable items.">
                                        <a href="delegate.html">Drag Delegation</a>
                                    </li>
                                
                            
                                
                                    <li data-description="Using DD.Delegate to support dragging multiple items and dropping them onto a Drop Target.">
                                        <a href="delegate-drop.html">Drag Delegation with a Drop Target</a>
                                    </li>
                                
                            
                                
                                    <li data-description="How to use Drag plugins with a DD Delegate based solution.">
                                        <a href="delegate-plugins.html">Using Drag Plugins with Delegate</a>
                                    </li>
                                
                            
                                
                                    <li data-description="This example shows how to make a sortable list using Custom Event Bubbling.">
                                        <a href="list-drag.html">List Reorder w/Bubbling</a>
                                    </li>
                                
                            
                                
                                    <li data-description="This example shows how to make a sortable list using Custom Event Bubbling and Node Scrolling.">
                                        <a href="scroll-list.html">List Reorder w/Scrolling</a>
                                    </li>
                                
                            
                                
                                    <li data-description="How to make an animated node a Drop target.">
                                        <a href="anim-drop.html">Animated Drop Targets</a>
                                    </li>
                                
                            
                                
                                    <li data-description="Example Photo Browser application.">
                                        <a href="photo-browser.html">Photo Browser</a>
                                    </li>
                                
                            
                                
                                    <li data-description="Portal style example using Drag &amp; Drop Event Bubbling and Animation.">
                                        <a href="portal-drag.html">Portal Style Example</a>
                                    </li>
                                
                            
                                
                            
                                
                            
                        </ul>
                    </div>
                </div>
            

            
                <div class="sidebox">
                    <div class="hd">
                        <h2 class="no-toc">Examples That Use This Component</h2>
                    </div>

                    <div class="bd">
                        <ul class="examples">
                            
                                
                            
                                
                            
                                
                            
                                
                            
                                
                            
                                
                            
                                
                            
                                
                            
                                
                            
                                
                            
                                
                            
                                
                            
                                
                            
                                
                            
                                
                            
                                
                            
                                
                                    <li data-description="Working with multiple YUI instances.">
                                        <a href="../yui/yui-multi.html">Multiple Instances</a>
                                    </li>
                                
                            
                                
                                    <li data-description="Use StyleSheet to adjust the CSS rules applying a page theme from user input">
                                        <a href="../stylesheet/stylesheet-theme.html">Adjusting a Page Theme on the Fly</a>
                                    </li>
                                
                            
                        </ul>
                    </div>
                </div>
            
        </div>
    </div>
</div>

<script src="../assets/vendor/prettify/prettify-min.js"></script>
<script>prettyPrint();</script>

</body>
</html>
